Summary

Closes #185. Three-line change at the three viewer.h3Points.add() / viewer.samplePoints.add() sites, plus one new top-level constant.

Root cause

Cluster and sample point primitives are placed at altitude=0 (the WGS84 ellipsoid surface). Cesium world terrain is enabled by default, so terrain mesh in hilly regions rises hundreds to thousands of meters above ellipsoid — sea-level primitives are physically underground there and get depth-culled by Cesium's standard per-pixel depth test.

This is why the issue manifests over the Troodos range (Cyprus) and the hill country around Birmingham, AL but not over coastal/flat regions.

Diff

// New constant alongside SOURCE_VALUES / DEFAULT_POINT_BUDGET:
POINT_DEPTH_TEST_DISTANCE = 2.0e6  // meters; see doc comment for rationale

// Three .add() sites each gain one property:
viewer.h3Points.add({
    ...,
    scaleByDistance: scalar,
    disableDepthTestDistance: POINT_DEPTH_TEST_DISTANCE,  // issue #185
});

Why bounded (2.0e6), not POSITIVE_INFINITY

PR #181 tried disableDepthTestDistance: POSITIVE_INFINITY and was reverted via #183 because it caused:

• Back-side-of-globe primitive bleed-through (points on the FAR hemisphere rendered through the Earth)
• Broken hover/click pickability

A bounded 2,000 km distance preserves globe-ellipsoid occlusion at long range (no back-side bleed) while bypassing terrain occlusion at every interactive zoom altitude (point mode <120 km, res8 ≤300 km, res6 ≤3,000 km).

Experimental verification

Runtime-patched the live deploy at https://isamples.org/explorer.html with the user's western Cyprus / point altitude URL. Compared four toggles:

The dots that appear under T2/T3 are not new data — they were always loaded, just depth-culled in T0.

Local preview run of quarto preview explorer.qmd against the same URL with this PR applied shows the same restored visibility.

What was ruled out

The hypotheses listed in #185's body:

• Alpha-fill blending into bright satellite imagery — would not explain point-mode dots (pixelSize: 6, scaled to ~18-48 px) disappearing entirely.
• Cesium PointPrimitive shader artifact at certain pixelSize/outlineWidth ratios — T5 force-bigger-pixelSize alone didn't restore visibility on hilly terrain; T3 did.
• Atmosphere/translucent ocean layer — PR explorer: fix halo terrain occlusion via scene.globe.depthTestAgainstTerrain (v2) #184 already ruled out global scene settings as the cause.
• GPU/DPR-specific — the bug reproduces in headless chromium at default viewport, so not high-DPR-specific.
• heightReference — Cesium.PointPrimitive does not support heightReference (only PointGraphics / Entity API does). Switching the explorer to entities would be a much bigger lift than this PR.

Test plan

• Cyprus / Troodos (user's repro) — visit https://isamples.org/explorer.html#v=1&lat=34.9228&lng=33.4248&alt=101686&heading=360.0&mode=point with this PR applied; confirm sample dots visible across Cyprus interior, not just the coastline.
• Birmingham, AL (original explorer: halo crescents / disappearing dots over hilly terrain (root cause not yet identified) #185 repro) — visit https://isamples.org/explorer.html#v=1&lat=33.2706&lng=-86.2375&alt=311435&heading=360.0; confirm halos / dots visible over hill country.
• No regression — back-side of globe: zoom out to world view, rotate so a populated region (e.g. central US) is on the far side of the Earth. Confirm dots from that region do NOT bleed through and render in front of the visible hemisphere. (This was the PR explorer: fix halo cutoff over terrain (disableDepthTestDistance) #181 failure mode.)
• No regression — pickability: hover over a dot in cluster and point mode at various altitudes; confirm the hover tooltip appears and clicking opens the side panel. (PR explorer: fix halo cutoff over terrain (disableDepthTestDistance) #181 also broke this.)
• Coastal / flat regions still render fine — visit any coastal location at point altitude; confirm dots still appear (no visual change expected, but make sure the fix didn't break what wasn't broken).
• No regression at world view (alt > 2,000 km) — the bypass is bounded at 2,000 km; above that, depth test is active again. Visit alt=8,000,000 (≈8,000 km) world view; confirm clusters render normally and don't show back-side bleed.

Refs

• explorer: halo crescents / disappearing dots over hilly terrain (root cause not yet identified) #185 — parent issue (with prior repro, hypotheses, experimental confirmation in issue comment)
• explorer: fix halo cutoff over terrain (disableDepthTestDistance) #181 / Revert "explorer: fix halo cutoff over terrain (disableDepthTestDistance)" (#181) #183 / explorer: fix halo terrain occlusion via scene.globe.depthTestAgainstTerrain (v2) #184 — prior fix attempts, all reverted/closed
• explorer: native Cesium toolbar + prominent share button + a11y halos #180 — original PR that introduced the white halos

🤖 Generated with Claude Code